____________________________________________________________________

The following gives a brief set of guidelines before going in-depth with the ProDk.chm help file in order to port the target.

0.CONTENTS:

1. Basic requirements.
2. Overview of initial steps required to carry out the porting.
3. Tips for porting.

1.Basic requirements

• Multi-tasking OS
• ANSI 'C' development chain for the target system

• The Following OS features:
  • TCP/IP BSD socket interface - To communicate with the workbench and/or for PLC to PLC binding links communication.
  • Serial line driver - To drive the serial communication port. Basically read/write of characters. Used only to communicate with the workbench.
  • Time management - Any clock (like the system tick one) can be used to give a beat. The ISaGRAF time unit is the ms. Therefore, the maximum possible accuracy is 1ms.
  • Shared memory spaces - the same memory area needs to be accessed from various tasks.
  • Semaphores -  Binary semaphores for task synchronization. Mutual exclusion semaphores for shared data access from various tasks.
  • Message queues -  Tasks need to communicate each other using enhanced messages. The content of messages is not meaningful for the porting.  A message queue can be seen as a shared FIFO buffer protected by semaphores to manage multiple access from various tasks.
  • Task management - Tasks needs to be started/terminated according the application configuration and debug commands.
  • Storage device management (hard disk, ram disk, flash,...) for non-volatile information storage. Also Used for application code backup or additional module storage such as the symbol table. A simplified directory browse-like feature is also required to get the list of resources for which the application code has been stored.

These features are solicited through a set of routines. They have a well specified interface described in the ProDk.chm help file. Commented empty routines are provided in the NewOS directory of the CD-ROM.

Implementing  the porting mostly consists in filling-in these routines and therefore in some way "mapping" ISaGRAF required features to the ones available for the OS.

• Static data allocation

Here "static data" refers to any 'C' variable not allocated in the stack (basically global variables).

Various tasks share the same portion of code. This is basically the case for the virtual machine task that may be launched several times. It is also the case for the system layer library that is used by all tasks.

In this case, the OS must re-allocate static data for each task instance.

This is not the case for a 'kernel' - like OS or what is commonly called a multithreaded OS. In such cases the OS must as a minimum provide a way to store a few pointers (3 or 4) with a task context switch. Then a solution consists in "manually programming" the data allocation in the very first task initialization step. Such a solution is provided within source files for VxWorks OS.

2.Overview of initial steps required to carry out the porting

• Check that the basic requirements detailed above are fulfilled
• Copy the NewOs directories from the CD-ROM to your development environment.

• Define your target

This must be done both on the workbench side using the PLCTools.mdb utility (or TDBuild.exe) and on the target side by completing the IsaSys\dsys0def.h file. Obviously information entered on the workbench side must match with that entered on the target side.

A specific "TO DO" mark in dsys0def.h file shows you what to do as a first step. Some "#error" pragma are used to catch your attention if you forget to give an important piece information.

• Define your networks

Used for resource-to-resource binding links And/Or the workbench debugger communication. This must be done on the workbench side using the PLCTools.mdb utility (or TDBuild.exe). Most of the time you will need HSD (local memory exchanges). You can also copy ETCP And/Or IsaRSI if you intend to use TCP/IP and/or an RS232 link. Obviously on the target side, the network is to be implemented as a binding driver And/Or an IXL driver. HSD, ETPC, IsaRSI come with the standard port. You can of course, as a separate step, also implement new communication media.

• Build makefiles

As described in greater detail in ProDk.chm, the target is composed of various components. From the compilation point of view this corresponds to various makefiles. For example makefiles to link and generate a task or another (or process, or executable according to the system terminology) or makefiles to build a library or another. Such information is available in NewOs\MakPrDK.txt.

• Compile files and build the target  

Once makefiles are ready, just use them and compile the target. This step ensures that all files compiles without any error.

Of course, you get a target that cannot run. The next step shows you how to make it run.

• Implement required interfaces

Note that it is highly recommended to fully validate each single interface implementation individually before making  a global target test.  

Interfaces to start with -  The easiest one to start with is time management:

• Time management: IsaSys\dsys0tim.c    
• Shared memory spaces: IsaSys\dsys0spc.c as a first step you can skip the part about non-volatile backup storage.
• Message queues: IsaSys\dsys0msq.c
• Task management: IsaCmg\dcmg0tsk.c
• TCP/IP BSD socket interface: Etcp\detc0soc.c Etcp\detc0soc.h

•     AND/OR

• Serial line driver: IsaRsi\drsi0com.c IsaRsi\drsi0com.h

At this stage you may be able to start the target (launch the configuration manager) and to establish the communication with the workbench through TCP/IP or Serial line according what you have implemented. We advise you to start with a very simple project with just one resource and only internal variables of course.

Do not forget, in the workbench application, to enter the right target in the configuration properties (or resource properties) and to enter the right network communication parameters before compiling (Hardware Architecture view).

Then you may be able to download and debug your application.

With such an implementation, you basically cannot:

• Save resource code.
• Start a resource from saved code.
• Download symbols table (or other future modules).
• Use binding links (TCP/IP (ETCP) or Local (HSD)).

•  

Then to allow Save/Restore of resource code you may continue with the implementation of non-volatile storage device management by coding the following interfaces:

• Shared memory spaces: IsaSys\dsys0spc.c

part about backup storage you skipped in the first step.

• Stored resources browse: IsaCmg\dcmg0fil.c

Then to allow symbols table (and other future modules) management you may continue with non-volatile storage device management, implementing the following interfaces:

• Data in sequential access: IsaSys\dsys0dsa.c

Then to allow binding links you may continue implementing the following interfaces:

• Semaphores: IsaSys\dsys0sem.c

3.Tips for porting   

* Functions starting with an 'X' (X-----()) refer to routines that have an external file scope BUT are not part of public interfaces. They have been coded for convenience and coding modularity within the library. Basically, you can change the 'X' functions with your OS trigram (3 letters identifying your OS) as done within ICS Triplex ISaGRAF supported OS implementations.

Following the same idea, IsaSys\dext0---.h are dedicated for OS-specific declarations and definitions. For example all X-----() functions are declared in dext0pro.h. Basically, you can change the 'ext' with your OS trigram as done within ICS Triplex ISaGRAF supported OS implementations.

* XsysObjNameGet() & dsysPathNameGet()

When implementing "space" / "message queue" / "semaphore" management, if your OS needs a named object, you can use the XsysObjNameGet() function.

In the same way, when implementing storage device management you can use the dsysPathNameGet() function to get the full path name of different objects (space, dsa) to store. You may also use dsysPathNameGet() to just get the path of the storage device.

• dsysPathNameGet() uses XsysObjNameGet().

• In fact, the path is retrieved through the   _dsysPrjPathSet() routine which you can complete to get the desired path. You can for example retrieve it from a startup parameter called "PrjPath" using the dsysArgGet() service as is done in some ICS Triplex ISaGRAF supported OS implementations.

____________________________________________________________________

Copyright © 1999-2009 ICS Triplex ISaGRAF Inc. All rights reserved.